解決 .NET Docker 容器中缺少字型檔的問題

TLDR

• 問題原因：.NET 官方 Docker 映像檔（如 Debian-based）為了縮減體積，預設未安裝字型套件，導致 /usr/share/fonts 路徑缺失。
• 解決方案：需在 Dockerfile 中安裝 ttf-mscorefonts-installer 與 fontconfig，並執行 fc-cache 更新字型快取。
• 版本差異：Debian 11 (.NET 6) 使用 /etc/apt/sources.list 設定來源；Debian 12 (.NET 8) 則改用 /etc/apt/sources.list.d/debian.sources。

---

Docker 容器中的字型缺失問題

什麼情況下會遇到這個問題：當應用程式需要進行圖形處理（如產生報表、繪圖）或依賴特定字型渲染時，若使用 Visual Studio 預設產生的 .NET Dockerfile，會發現容器內缺少 /usr/share/fonts 目錄，導致字型載入失敗。

這是因為 mcr.microsoft.com/dotnet/aspnet 映像檔採用精簡版 Linux 發行版，未預裝字型套件。針對 .NET 6 (Debian 11) 環境，可透過以下方式在 Dockerfile 中補齊字型：

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base

# 啟用 contrib 來源並安裝字型套件
RUN sed -i'.bak' 's/$/ contrib/' /etc/apt/sources.list
RUN apt-get update; apt-get install -y ttf-mscorefonts-installer fontconfig

# 強制重新整理字型快取
RUN fc-cache -f -v

WORKDIR /app
# ... 後續建置步驟

---

處理 .NET 8 Dockerfile 的環境差異

什麼情況下會遇到這個問題：當升級至 .NET 8 (Debian 12) 時，若直接套用上述針對 Debian 11 的 sed 指令，會因找不到 /etc/apt/sources.list 檔案而導致建置失敗（Exit code 21）。

Debian 12 已將套件來源設定改為 /etc/apt/sources.list.d/debian.sources。針對 .NET 8 的修正方式如下：

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

# 針對 Debian 12 修改來源設定
RUN sed -i 's/^Components: main$/& contrib/' /etc/apt/sources.list.d/debian.sources

# 安裝字型套件
RUN apt-get update; apt-get install -y ttf-mscorefonts-installer fontconfig

# 重新整理字型快取
RUN fc-cache -f -v

USER app
WORKDIR /app
# ... 後續建置步驟

WARNING

安裝 ttf-mscorefonts-installer 時，請確保環境允許自動化安裝，並確認相關授權條款符合專案規範。

---

異動歷程

1. 2024-08-09

   • 初版文件建立。